home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / music_utilities / pt013.dms / pt013.adf / Programmers / PlayerLibrary / library.doc < prev    next >
Text File  |  1991-08-25  |  9KB  |  323 lines
  1. ***************************************************************************
  2. ***************************************************************************
  3.  
  4. Instructions for using "medplayer.library" V2.00, by Teijo Kinnunen.
  5.  
  6. ***************************************************************************
  7. ***************************************************************************
  8.  
  9.  
  10.         medplayer.library
  11.         ~~~~~~~~~~~~~~~~~
  12.  
  13. "medplayer.library" is a shared library, which can be used to load and play
  14. MED/OctaMED  4-channel modules You can call its functions from any language
  15. which supports library calls (C, Assembler, Basic...)
  16.  
  17. First  you  must  install  "medplayer.library" to your LIBS:  drawer (click
  18. Install_Libraries  to  do that).  You can also load it with ARP's "loadlib"
  19. command.
  20.  
  21. There's  a  header  file  'libproto.h'  that  contains  the  prototypes and
  22. #pragmas for use with SAS/Lattice C V5.
  23.  
  24. Here's  the  complete  list of the functions in "medplayer.library" (in RKM
  25. autodoc-style):
  26.  
  27. ---------------------------------------------------------------------------
  28. ---------------------------------------------------------------------------
  29.  
  30. GetPlayer
  31.  
  32. NAME
  33.     GetPlayer -- get and initialize the player routine
  34.  
  35. SYNOPSIS
  36.     error = GetPlayer(midi)
  37.     D0                D0
  38.  
  39. FUNCTION
  40.     This routine allocates the audio channels and CIAB timer A/B
  41.     and prepares the interrupt. If "midi" is nonzero, serial
  42.     port is allocated and initialized. You should call this
  43.     routine when your programs starts up.
  44.  
  45. INPUTS
  46.     midi =  0 no midi, 1 set up midi. When you use a song that
  47.         has only Amiga samples, there's no reason to allocate
  48.         the serial port. Then set midi to 0.
  49.  
  50. RESULT
  51.     If everything is OK, GetPlayer() returns zero. If initialization
  52.     failed or somebody else is currently using the library, then
  53.     GetPlayer() returns nonzero value.
  54.     NOTE: Even if GetPlayer() returned an error, you can still call
  55.           the library functions without making harm. They just won't
  56.           work (except LoadModule(), UnLoadModule(), RelocModule()
  57.           and GetCurrentModule(), which always work).
  58.  
  59. SEE ALSO
  60.     FreePlayer
  61.  
  62. ---------------------------------------------------------------------------
  63. ---------------------------------------------------------------------------
  64.  
  65. FreePlayer
  66.  
  67. NAME
  68.     FreePlayer -- free the resources allocated by GetPlayer()
  69.  
  70. SYNOPSIS
  71.     FreePlayer()
  72.  
  73. FUNCTION
  74.     This routine frees all resources allocated by GetPlayer().
  75.     Remember always call this routine before your program
  76.     exits. It doesn't harm to call this if GetPlayer() failed.
  77.     If you don't call this function during exit, audio channels,
  78.     timer etc. will remain allocated until reboot.
  79.  
  80. SEE ALSO
  81.     GetPlayer
  82.  
  83. ---------------------------------------------------------------------------
  84. ---------------------------------------------------------------------------
  85.  
  86. PlayModule
  87.  
  88. NAME
  89.     PlayModule -- play module from the beginning
  90.  
  91. SYNOPSIS
  92.     PlayModule(module)
  93.                A0
  94.  
  95. FUNCTION
  96.     This routine starts to play the module from the beginning.
  97.     The module can be obtained by calling LoadModule() or it can
  98.     be incorporated directly into your program. The module has to
  99.     be relocated before calling PlayModule()!
  100.  
  101. INPUTS
  102.     module = pointer to the module.
  103.  
  104. SEE ALSO
  105.     ContModule, StopPlayer
  106.  
  107. ---------------------------------------------------------------------------
  108. ---------------------------------------------------------------------------
  109.  
  110. ContModule
  111.  
  112. NAME
  113.     ContModule -- continue playing the module from where it stopped
  114.  
  115. SYNOPSIS
  116.     ContModule(module)
  117.                A0
  118.  
  119. FUNCTION
  120.     ContModule() functions just like PlayModule() except if you
  121.     have stopped playing with StopPlayer(), the playing will
  122.     continue where it stopped. When you play the module first
  123.     time, you should use PlayModule().
  124.  
  125. INPUTS
  126.     module = pointer to module.
  127.  
  128. SEE ALSO
  129.     PlayModule, StopPlayer
  130.  
  131. ---------------------------------------------------------------------------
  132. ---------------------------------------------------------------------------
  133.  
  134. StopPlayer
  135.  
  136. NAME
  137.     StopPlayer -- stops playing immediately
  138.  
  139. SYNOPSIS
  140.     StopPlayer()
  141.  
  142. FUNCTION
  143.     Stop.
  144.  
  145. SEE ALSO
  146.     PlayModule, ContModule
  147.  
  148. ---------------------------------------------------------------------------
  149. ---------------------------------------------------------------------------
  150.  
  151. DimOffPlayer
  152.  
  153. NOTE
  154.     This is an obsolete function! It was removed in V2 of the library,
  155.     and it now just does StopPlayer()!
  156.  
  157. ---------------------------------------------------------------------------
  158. ---------------------------------------------------------------------------
  159.  
  160. SetTempo
  161.  
  162. NAME
  163.     SetTempo -- modify the playing speed
  164.  
  165. SYNOPSIS
  166.     SetTempo(tempo)
  167.              D0
  168.  
  169. FUNCTION
  170.     If you want to modify the playback speed, you can call this one.
  171.     This number should be 1 - 240. Note that tempos 1 - 10 are
  172.     recognized as SoundTracker tempos.
  173.  
  174. INPUTS
  175.     tempo = new tempo
  176.  
  177. ---------------------------------------------------------------------------
  178. ---------------------------------------------------------------------------
  179.  
  180. LoadModule
  181.  
  182. NAME
  183.     LoadModule -- load a MED module from disk and relocate it
  184.  
  185. SYNOPSIS
  186.     module = LoadModule(name)
  187.     D0                  A0
  188.  
  189. FUNCTION
  190.     When you want to load a module from disk, call this function.
  191.     The function loads only MED modules (MMD0). It doesn't load
  192.     Tracker-modules, MED songs or object files. Only MMD0's
  193.     (MMD0 is the identification word at the beginning of the file).
  194.     Because the module contains many pointers, they must be
  195.     relocated. This function relocates the module automatically.
  196.     If you include the module as a binary file converted with
  197.     Objconv, YOU must relocate it. This is an easy thing to do.
  198.     Just call RelocModule().
  199.  
  200. INPUTS
  201.     name = pointer to file name (null-terminated)
  202.  
  203. RESULT
  204.     module = pointer to module. If failed to load for some reason
  205.              (disk error, out of memory, not a module), zero will
  206.           be returned.
  207.  
  208. SEE ALSO
  209.     UnLoadModule
  210.  
  211. ---------------------------------------------------------------------------
  212. ---------------------------------------------------------------------------
  213.  
  214. UnLoadModule
  215.  
  216. NAME
  217.     UnLoadModule -- frees the module from memory
  218.  
  219. SYNOPSIS
  220.     UnLoadModule(module)
  221.                  A0
  222. FUNCTION
  223.     When you don't need the module anymore, you MUST free the
  224.     memory it has used. Use this routine for it. Remember to
  225.     stop the player before unloading the module it is playing.
  226.  
  227.     NOTE: unload only those modules which are loaded with
  228.     LoadModule(). If you attempt to free module which is a part
  229.     of the program, you will cause guru 81000009/81000005.
  230.  
  231. INPUTS
  232.     module = pointer to module. If zero, nothing happens.
  233.  
  234. SEE ALSO
  235.     LoadModule
  236.  
  237. ---------------------------------------------------------------------------
  238. ---------------------------------------------------------------------------
  239.  
  240. GetCurrentModule
  241.  
  242. NAME
  243.     GetCurrentModule -- returns the address of module currently playing
  244.  
  245. SYNOPSIS
  246.     module = GetCurrentModule()
  247.     D0
  248.  
  249. FUNCTION
  250.     Simply returns the pointer of the module, which is currently
  251.     playing (or if player is stopped, which was played last). This
  252.     works also if some other task is currently playing. In this case,
  253.     because of multitasking, you should have no use for the value
  254.     (the module can be already unloaded). You may ask what use this
  255.     function has. Well, I'm not sure, but because this function
  256.     takes only 2 machine language instructions (8 bytes of memory)
  257.     there's not much harm of it.
  258.  
  259. RESULT
  260.     module = pointer to current module
  261.  
  262. ---------------------------------------------------------------------------
  263. ---------------------------------------------------------------------------
  264.  
  265. ResetMIDI
  266.  
  267. NAME
  268.     ResetMIDI -- reset all pitchbenders and modulation wheels and
  269.                  ask player to resend the preset values
  270.  
  271. SYNOPSIS
  272.     ResetMIDI()
  273.  
  274. FUNCTION
  275.     This function resets pitchbenders and modulation wheels on all
  276.     MIDI channels. It also asks the player to send again the
  277.     preset change requests for all instruments, so that the presets
  278.     will be correct if the user has changed them. It performs the
  279.     same function as MED's Ctrl-Space.
  280.  
  281. ---------------------------------------------------------------------------
  282. ---------------------------------------------------------------------------
  283. NOTE: THE FOLLOWING FUNCTIONS ARE ONLY AVAILABLE IN MEDPLAYER.LIBRARY V2
  284. OR LATER, BE SURE THAT YOU'RE REALLY USING V2 OF THE LIBRARY
  285. e.g.  MEDPlayerBase = OpenLibrary("medplayer.library",2);
  286. ---------------------------------------------------------------------------
  287. ---------------------------------------------------------------------------
  288.  
  289. SetModnum
  290.  
  291. NAME
  292.     SetModnum -- select the number of the song (in multi-module)
  293.  
  294. SYNOPSIS
  295.     SetModnum(modnum)
  296.           D0
  297.  
  298. FUNCTION
  299.     Use this function to set the number of song you want to play.
  300.     Call this before PlayModule(). 0 is the first song, 1 is the
  301.     second, and so on. If the module is not a multi-module, this
  302.     function has no affection.
  303.  
  304. ---------------------------------------------------------------------------
  305. ---------------------------------------------------------------------------
  306.  
  307. RelocModule
  308.  
  309. NAME
  310.     RelocModule -- relocate module
  311.  
  312. SYNOPSIS
  313.     RelocModule(module)
  314.             A0
  315.  
  316. FUNCTION
  317.     This function relocates the module. It should be used if you've
  318.     incorporated the module with Objconv program before using the
  319.     module. Note that LoadModule() automatically relocs everything.
  320.  
  321. ---------------------------------------------------------------------------
  322. ***************************************************************************
  323.